Skip to main content

Setup Webhook Forwarding URL

Overview​

The Setup Webhook API registers a forwarding webhook URL for a specific application. This enables routing of identity verification events from providers (like Sumsub) to application-specific endpoints, allowing for tenant-specific callbacks and downstream system integrations.

Authentication​

This endpoint requires authentication. See API Authentication for detailed requirements and how to obtain credentials.

Endpoint​

POST /api/client-credentials/setup-webhook

Path Parameters​

  • applicationId (required): The unique identifier of the application for which to configure the webhook

Request Body​

Interface Definitions​

interface SetupWebhookRequest {
   webhookUrl: string;
}

interface SetupWebhookResponse {
   statusCode: number;
   data: {
      message: string;
      applicationId: string;
      webhookUrl: string;
   };
}

Request Example​

{
   "webhookUrl": "https://your-domain.com/api/kyc/webhook"
}

Response Structure​

Success Response​

{
   "statusCode": 200,
   "data": {
      "message": "Webhook setup successfully",
      "applicationId": "68ef2012876e76eb50626f29",
      "webhookUrl": "https://your-domain.com/api/kyc/webhook"
   }
}

Error Response​

{
   "statusCode": 400,
   "message": "Invalid webhook URL",
   "errors": [
      {
         "field": "webhookUrl",
         "message": "URL must use HTTPS protocol"
      }
   ]
}

Field Validation Requirements​

Webhook URL Validation​

  • Protocol: Must use HTTPS for security
  • Format: Must be a valid URL format
  • Accessibility: Should be publicly accessible for webhook delivery
  • Response: Endpoint should respond to POST requests
  • Authentication: Consider implementing webhook signature verification

Required Fields​

  • webhookUrl: Valid HTTPS URL string (required)

Usage Guidelines​

Webhook Configuration​

The webhook URL will receive POST requests containing:

  • New application creation events (application.created)
  • KYC verification status updates
  • Document processing results
  • Identity verification completion events

Event Forwarding Flow​

  1. Trigger: A new application is submitted, or an identity provider (Sumsub) sends an event
  2. Event Processing: System processes and validates the event
  3. Forwarding: Event is posted to the configured organization webhook URL
  4. Delivery: Failed deliveries are logged; implement idempotent handling on your side

Integration Patterns​

  • Tenant-Specific Routing: Configure different endpoints for different tenants
  • Event Filtering: Filter events based on payload shape (eventType vs KYC fields)
  • Retry Logic: Implement proper retry mechanisms for failed deliveries
  • Signature Verification: Validate webhook authenticity using signatures

Webhook Payload Structure​

Event Types​

Outbound webhooks currently include:

  • application.created: Fired when a new application is successfully submitted (not on resubmit)
  • KYC status payloads: Forwarded identity verification updates (no eventType field; identified by applicantId / status)

Application Created Payload​

Sent after a successful PUT /api/applications/submit that creates a new application (request without applicationId), when a webhook URL is configured.

interface ApplicationCreatedWebhookPayload {
   eventType: 'application.created';
   applicationId: string;
   status: string;
   externalReference?: string;
}
{
   "eventType": "application.created",
   "applicationId": "68ef2012876e76eb50626f29",
   "status": "pending",
   "externalReference": "CRM-12345"
}
  • externalReference is included only when set on the application
  • If no webhook URL is configured for the organization, the notification is skipped

KYC Status Payload​

interface SumsubStatusWebhookPayload {
   applicantId: string;
   status: string;
   applicationId?: string;
   externalReference?: string;
   reason?: string;
   documents?: string[];
}
{
   "applicantId": "68edee456a03b3a57aff8040",
   "status": "approved",
   "applicationId": "68ef2012876e76eb50626f29",
   "externalReference": "CRM-12345",
   "documents": [
      "https://storage.googleapis.com/.../document1.jpeg",
      "https://storage.googleapis.com/.../document2.jpeg"
   ]
}

Error Handling​

Common Error Scenarios​

  • 400 Bad Request: Invalid webhook URL format or protocol
  • 401 Unauthorized: Authentication failure
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Application not found
  • 409 Conflict: Webhook URL already configured
  • 500 Internal Server Error: Temporary service issues

Webhook Delivery Errors​

The system handles webhook delivery failures with:

  • Retry Logic: Exponential backoff with maximum retry attempts
  • Dead Letter Queue: Failed events are stored for manual review
  • Status Monitoring: Track delivery success rates and failure patterns
  • Alerting: Notifications for persistent delivery failures

Security Considerations​

HTTPS Requirement​

  • All webhook URLs must use HTTPS for secure transmission
  • SSL certificate validation is performed during setup
  • Insecure connections are rejected to protect sensitive data

Signature Verification​

Consider implementing webhook signature verification:

  • Generate and validate HMAC signatures
  • Include timestamp validation to prevent replay attacks
  • Use secure secret management for signing keys

Data Protection​

  • Webhook payloads contain sensitive personal information
  • Implement proper access controls on receiving endpoints
  • Log webhook events for audit and compliance purposes
  • Follow data retention policies for webhook data

Usage Examples​

Basic Setup​

curl -X POST \
   'https://api.speedydd.com/api/applications/68ef2012876e76eb50626f29/setup-webhook' \
   -H 'X-App-ID: your-app-id' \
  -H 'X-API-Key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "webhookUrl": "https://your-domain.com/api/kyc/webhook"
  }'

Best Practices​

Endpoint Design​

  1. Idempotency: Handle duplicate webhook deliveries gracefully
  2. Fast Response: Return HTTP 200 quickly to acknowledge receipt
  3. Async Processing: Process webhook data asynchronously
  4. Error Handling: Return appropriate HTTP status codes

Monitoring and Maintenance​

  1. Health Checks: Monitor webhook endpoint availability
  2. Performance Metrics: Track processing times and success rates
  3. Log Analysis: Monitor for patterns in webhook failures
  4. Regular Testing: Validate webhook functionality periodically
Integration Tip

Set up webhook monitoring and alerting to ensure you don't miss important verification events that could impact your user experience.

Important

Always use HTTPS URLs for webhooks and implement proper signature verification to ensure security and authenticity of webhook events.